HAM Radio 3.2

home *** CD-ROM | disk | FTP | other *** search

/ HAM Radio 3.2 / Ham Radio Version 3.2 (Chestnut CD-ROMs)(1993).ISO / packet / gil101 / gilmain.doc < prev next >

Wrap

Text File | 1991-04-03 | 55KB | 1,378 lines

GIL (c) GRAPHICS INTERCHANGE LANGUAGE Version 1.01 A Public Domain Program Copyright 1991 by Glenn L. Williams Protected by Federal Copyright Law. Permission granted for non-commercial use and distribution. Not to be used for commercial advantage. All rights reserved. This document contains (TBD) pages. This is a draft copy for the beta release. IBM(TM), AT&T(TM), Olivetti(TM), Hercules(TM), are trademarks of those well-known companies International Business Machines, American Telephone and Telegraph, Olivetti of Italy, and Hercules Corp. If other trademarks accidentally were omitted from this list I apologize. Disclaimer ---------- The author shall have no liability or responsibility to user or any other person or entity with respect to any loss or damage caused or alleged to be caused directly or indirectly through the use of this documentation or the GIL program. Distribution and Use of GIL ------------------------- GIL is a copyrighted program. All rights are retained by the author. GIL is not to be sold; nor is it to be used for commercial purposes. You may freely distribute GIL, and you are encouraged to do so, but you may not charge for doing so, except as permitted below. The following files should be included in any distribution: GIL.EXE GIL.DOC GILMAIN.DOC PENG.GIL QSL.GIL GIL is hereby placed into the public domain, but cannot be used or sold with a product supplied by a profit making corporation. GIL may be used by any amateur radio operator, in amateur radio (non-profit) operating environments, and also by any not-for-profit organization, or any government agency, as long as product is not mixed in or sold with any for sale product costing more than $5.00 U.S. dollars, except as noted in paragraphs below. I.e. this program may be included in its archived (zip or arc) format or unarchive format to support other shareware but all rights to this product are to be retained in the public domain and the author's copyrights remain intact. This product and its documentation in archived format may be uploaded to public domain bulletin boards, except no license is granted hereby for any commercial use or copyright transfer to any bill-for-service data base or bulletin board service, including, among others, BIX(TM), PRODIGY(TM), and COMPUSERVE(TM). This utility is being provided free of charge for the main benefit of amateur radio operators worldwide. In the U.S.A. amateur radio is a hobby that is infinitely enjoyable for young and old. We "hams" cannot receive a profit from anything we do in amateur radio, therefore, this program is freely available and the author expects no profit from it. For this reason, this program and the .GIL file technique are NEVER to be used as a source of income by any individual or corporation. The copyrights are not transferable. However, this software may be sold on floppy disk by vendors of freeware and shareware where the floppy disks are sold for no more than $5.00 each via mail order or at fleamarkets and hamfests. 1. Purpose ---------- The primary purpose behind GIL is to permit a convenient way for radio amateurs to send more than just plain ASCII text messages over the packet or RTTY radio links. Before GIL, there was no convenient way to transmit over the radio, or via bulletin board, reasonably small "files" containing enough information to reconstruct a good line drawing or cartoon, over the radio. 2. Starting GIL -------------------- If you have not already done so, please make a working copy of all GIL disk files and store away the disk on which you received GIL for safekeeping, and use the working copy when you want to run GIL. You may write protect the working copy because GIL will not usually write to the disk. (This applies to version 1.01 only. In the future releases the usage of the disk may change.) Your working disk should contain the following files: GIL.EXE (The GIL executable program) and several other .GIL format files for your enjoyment. Anyone wishing to send interesting new .GIL format files to the author would be highly appreciated. Also, new .GIL format files should be exchanged on packet and telephone bulletin boards!! 2.1 Interactive startup ------------------------ To run GIL in interactive mode, the following command syntax is used: Start from your DOS prompt with the command: GIL and when you receive the "GIL>" prompt, then type in ASCII commands that will be further described below . As each command is typed it will be listed on the screen, and then executed when you type the ENTER key. Just above the command line your most recent command is listed, and just below the command line (in some cases) are error messages. When you are done and wish to go back to DOS, use the ".bye" command to exit. Ultimately you may want to compose .GIL files with a text editor or word processor and then "batch" process them through the program. Further instructions below will describe the process in detail. 2.2 Non-interactive startup "BATCH MODE" ---------------------------- ------------ For straight ASCII file input mode, GIL accepts input from "stdin" redirection, as follows: GIL <[drive:][path][filename] ^ |......note this "<" character used for stdin input redirection. At the end of the drawing process, when you are done viewing the drawing, striking any key will clear the screen and return you to DOS. Anyone not familiar with "stdin" redirection should consult the operation of the DOS COMMAND.COM shell in his DOS manual. Therefore, just for the sake of getting some idea of what GIL can do, try the following command (VGA or EGA recommended): GIL <OPUS.GIL If you are an amateur radio operator, or if you have only a monochrome Hercules Graphics Adapter, try: GIL <QSL.GIL If you have a TSR utility such as GRAPHICS.COM (usually supplied with your DOS for CGA adapters), or EGAPRTSC.COM (for EGA adapters) you can also print the screen to an IBM or EPSON dot matrix printer, for obtaining a hard copy. That is, any TSR screen capture utility or printer utility capable of can "grab" the screen and "live" as a TSR (Terminate and Stay Resident) utility in your computer, can print the screen. However, at this time, the author has not had the time and resources to test all the TSRs's out there for compatibility with GIL. Nor is it expected at this time for GIL to cooperate with Microsoft Windows (TM) in any way other than as a "DOS" program. But since GIL interacts with your video card, it may or may not have a deleterious effect when operated under programs that use screen graphics as part of a "windows" or "shell" environment. WARNING: GIL will interact with your screen graphics adapter. As a result it will "trash" anything else on the screen. GIL has not been tested with all the graphics adapters in the world, and especially not with the monochrome versions of CGA, EGA, and VGA. The graphics routines are supported via the Microsoft Corporation "C" library for Quick-C 2.5 (TM) and any artifacts created by the standard library are not the fault of this author. NOTE: No compatibility with Microsoft Windows (TM) is implied in any way. Since GIL interacts with your video card, it may or may not have a deleterious effect when operated under programs that use screen graphics as part of a "windows" or "shell" environment. 2.2.1 BATCH MODE AND PIPING UNDER DOS ------------------------------------- The GIL program accepts input from either your command line inputs that you type in, or from "stdin" (standard input) using the redirection symbol "<". The latter permits GIL to accept "piped" input that is generated as the output of other programs. This piped input is very useful in batch (.BAT) files for displaying neutral files created by other DOS programs. (This opens up the possibility of "GIL extender" programs that create .GIL format neutral file output from sophisticated user interfaces!) For example, the DOS batch file below assumes that a program MAKER.COM creates a list of GIL commands. The list can be piped into GIL: COPY A:OLDDATA.DAT NEWDATA.DAT MAKER NEWDATA.DAT >GIL.OUT TYPE GIL.OUT | GIL With this example, MAKER operates on NEWDATA.DAT and by some magic process generates output (to "stdout") which is redirected to the file GIL.OUT (just so the GIL commands can be viewed later in case of a need to debug something). GIL.OUT is then "piped into" GIL. There is a real example of a need for this. For example, you receive via packet radio or telephone BBS a file with a really interesting drawing. But you want to try stretching the drawing in the Y axis direction on your screen. The file STRETCH.BAT can take care of it WITHOUT modifying the original .GIL data file. type aspect.gil >temp.gil type qsl.gil >>temp.gil type temp.gil |gilmain where the contents of aspect.gil is the single ASCII line: .aspect .5 In this example, the first stdout redirection in STRETCH.BAT creates the file TEMP.GIL. In the next line, QSL.GIL is appended to the end of the file TEMP.GIL with the ">>" syntax for append to file. Then TEMP.GIL is type-ed to stdout which is piped into GIL with the "|" syntax. SOAPBOX: users not aware of the utility of "stdin", "stdout", and piping, are missing some very useful features of DOS. 3.0 Neutral format "GIL" files ------------------------------- Since they are ASCII files, the .GIL type neutral files can be exchanged, sent to PBBS systems, E-Mailed, etc. to other users. Once the user has a copy of GIL.EXE, he/she can view the "drawings" and obtain hardcopies as described below. It is the author's original intended purpose for amateur radio operators to freely exchange copies of GIL.EXE and any associated .GIL type neutral files. GIL.EXE should be exchanged via telephone modem or floppy disk ("Nike Net") exchange. The ASCII .GIL type neutral files are intended for exchange via packet radio worldwide. These files carry the information for making a drawing, but being ASCII, they contain no information of an encrypted nature which would violate national or international regulations about exchanging encrypted information via amateur radio. Since these files are (usually) short, they will not "hog" precious radio bandwidth. IMPORTANT NOTE: when using a word processor, the user should be sure to save the final output as unformatted ASCII text output, without any of the special formatting usually supplied by a saved word processor file. That is, if you can view the final results with EDLIN or TYPE, then you are ready to submit the file data to GIL. WORDSTAR(TM), WORD(TM), WORDPERFECT(TM), FIRST PUBLISHER(TM), EXPRESS PUBLISHER(TM) and other document processing programs usually create other than "generic ASCII" file output. These files will cause great confusion if used with GIL while containing embedded word processor commands. 3.1 Use with Amateur Packet Radio and RTTY --- -------------------------------------- Since they are ASCII files, the .GIL type neutral files can be exchanged, sent to PBBS systems, E-Mailed, etc. to other users. Once the user has a copy of GIL.EXE, he/she can view the "drawings" and obtain hardcopies as described below. As described elsewhere, GIL accepts ASCII input in a "neutral" file format. It does NOT contain a "terminal emulator" mode in this release. Therefore, for use with amateur radio files, the data will have to be first downloaded and stored on disk from a radio or land line source. Next, since most sources of data will contain other ASCII protocols and "overhead" necessary for BBS operation, the files should be previewed first with a text editor or word processor to clean out the portions that GIL will treat as "garbage". 3.2 BRIEF INTRODUCTION OF THE SCREEN LAYOUT -------------------------------------------- DEFINITION OF VIEWPORT COORDINATES ---------------------------------- Once the program start up and establishes the type of graphics controller in use, it sets up some default colors and then issues a prompt line at the lower left part of the screen. This will be described in more detail below. Above the two text lines used for prompting, the rest of the screen should be blank. Actually, this is the graphical drawing area for the screen, called the viewport. Althought the different graphics controllers have different pixel dimensions in X and Y on the screen, the viewport coordinates are adjusted so YOU the user only use viewport coordinates, with the exception of the .text command which uses 22 rows of alphanumeric characters. The horizontal (X) dimension of the viewport is 1000. The correct pixel values run from 1 to 1000. However, via a technique called "clipping", all values that exceed the size of the viewport are treated as if valid, but the only lines and graphics that are drawn are the parts that fit inside ("are clipped off to fit inside") the viewport. The vertical (Y) dimension of the viewport is nominally at least 500. The exact value used depends on the type of graphics controller and the aspect ratio established by the .aspect command described in the Reference. This is somewhat cut and try due to the variability in graphics adapters. Viewport coordinates start from the top left corner of the screen (at a point called "1,1") and run to the lower right hand corner of the screen (at a point "1000,540") where "540" is merely the nominal height of the viewport as described above. Therefore, all drawing commands use viewport coordinates, NOT screen locations. (But all text commands use screen coordinates! -- The reason for this inconsistency is described elsewhere.) 3.3 HOW TO MAKE A DRAWING ------------------------- If you have some idea of what you want to do, you can just enter GIL interactively and test your commands on the screen to see what happens. Keep a list of what they do, and later you can type them into a file with a text editor (NOT necessarily a WORD PROCESSOR!) and then execute them in batch mode. Another way, especially good for use with existing drawings or new very complicated drawings, is to use lined paper or semi-transparent graph paper, ruled off and marked for use with GIL by showing the scale in viewpoint coordinates. For example, holding a sheet of paper in landscape orientation, with the long axis horizontal, mark off a large box 10 units (inches, or 20 mm) across and about 6 or 7 units high. With some graph paper, such as KEUFFEL AND ESSER(TM) graph sheets, with fine rulings (10 to the inch, every millimeter, etc.) you can set up a reasonably tight scale with good precision. Number the Y axis DOWN from the top and the X axis across from left to right. Then lay this graph paper over the object to be traced, or just sketch the object. In the case of a large scale mismatch, take your original drawing to a photocopy center with copiers with magnify/zoom capability and make a copy that is approximately the size you need for the graph paper. With the drawing transferred to the graph paper, you can then compose the commands for GIL. APOLOGY ------- Upon initial trial, some people may view this method of forced entry of awkward neutral file commands into the program as being rather clumsy and tedious. However, the resulting files are ASCII files with a very high degree of data compression already built in. This feature, and the fact that the data is editable by anyone on a PC with a text editor or word processor, results in relatively small files. Such files are suitable for transmission to amateur radio and telephone oriented bulletin board systems without the complications of data encryption or having to purchase expensive software graphics utilities. 3.4 VIDEO GRAPHICS CARD COMPATIBILITY ------------------------------------- This program was written for and compiled with Microsoft Quick-C (TM) V.2.5. For the remainder of this document, the compiler will just be called "C". Microsoft C functions for controlling video graphics were found to excecute faster then at least one other product on the market, and in addition, the support of the Hercules Graphics Card was found to be a definite boon. The program was written using the support of these functions, and therefore certain requirements of those functions also constrain the operation of the program. This program supports VGA, EGA, CGA, and HGC graphics controllers. In the attempt to provide a Graphics Interchange Language that spans the breadth of the differences between these graphics controllers, the user will have to be aware of some compromises: HGC (Hercules) - supports only monochrome video in 720 x 348 format CGA (Color Graphics Adapter) - supports only 4 colors, in low density 320 x 200 pixel format. EGA (Enhanced Graphics Adapter) - supports only 16 colors, in a higher density pixel format of 640 x 200. VGA (Video Graphics Adapter) - supports either 256 colors or 16 colors, in a 640 x 480 format. In addition, the C library used with the compiler also supports the AT&T Olivetti variants, known as "OVGA", "OEGA", and "OCGA". It also supports the MCGA adapter defined by IBM. Therefore support for these adapters has been included by intent, at least. But these remain untested. To achieve some compatibility between these graphics adapters, the usage of color in .GIL neutral files will result in certain problems for users restricted to CGA or HGC adapters. As a result, the program makes the following color choices and display choices. DISPLAY AREA ------------ All adapters are assumed to have no more than 320 horizontal rows of pixels. This establishes a constraint that keeps VGA displays from overwriting the command line, and keeps the format basically compatible with HGC. SCREEN COLORS ------------- COLORS SUPPORTED ---------------- SPELLING HGC CGA EGA VGA BLACK 0 x x(0) x x BLUE 1 x x GREEN 2 x x CYAN 3 x x RED 4 x x MAGENTA 5 x x BROWN 6 x x LTGRAY 7 x x DKGRAY 8 x x LTBLUE 9 x x LTGREEN 10 x(2) x x LTCYAN 11 x x LTRED 12 x(1) x x LTMAGENTA 13 x x YELLOW 14 x x WHITE 15 x x(3) x x NOTE: For HGC, all colors other than BLACK are forced to WHITE For CGA, color indexes not marked with "x" are right-shifted by two bits. I.e. "DKGRAY" which equals 8 (decimal) will become color index 2, which will appear as LTGREEN. LTMAGENTA (13) will become 3 (WHITE), etc. However, BLACK, LTGREEN, LTRED, and WHITE will work well with CGA. Therefore, if a drawing is to be presented to all users in an equal manner, obviously only BLACK and WHITE are useful, and for the most part any filled shapes should be kept as simple as possible. In some cases color can be used, but only if the intent is such that either monochrome just will not do, or when unexpected change of color also will not be serious. As will be described below, the ".require" command can be used to constrain operation of .GIL files with a particular adapter format. However, the ".require" commands can also be edited out in order to "try out" the files in case of curiousity. 3.5 COMPUTER COMPATIBILITY ISSUES ---------------------------------- By definition GIL will use the graphics screen of your PC-style computer. GIL will attempt to remember your default video modes and colors when it executes, so that upon exiting back to DOS, GIL will clean up and reset back to your defaults. But while GIL is executing, colors and modes may be changed. Every attempt has been made to make emergency termination of the program possible whenever certain error conditions occur: CTRL-C typed CTRL-BREAK typed Floating Point Error occurs (bugs, what bugs???) Other abnormal conditions When these actions occur, just before returning to DOS the program also attempts to restore your screen back to the condition in which it was found when GIL was invoked. However, there are no guarantees that this will always be possible. Attempting to exit GIL with a BREAK or CTRL-C keystroke may under some circumstances result in your video adapter being left in other than your default operating state. Conditions that may make normal termination impossible could possibly be caused by "other" Terminate and Stay Resident (TSR) programs residing in memory. "Other" programs include the wrong MSHERC.COM (in the case of your running a Hercules Graphics Adapter), or something other than the suggested print screen TSRs (GRAPHICS.COM, HPGRAPH.COM, EGAPRTSCRN, etc.). At present GIL does not make use of either the COM or LPT ports of the computer, nor does it write to disk. GIL requires DOS 3.3 or above, and will run in less than 512K of memory. GIL should not care whether it is executed from floppy or hard disk, since it assumes nothing but standard DOX path arguments for seeking files or data. GIL will also make use of the speaker device as a useful adjunct to screen graphics. Again, the same conditions apply as above, regarding aborting the program with "other" TSRs in memory. Under these conditions aborting GIL with BREAK or CTRL-C might leave your speaker "ON" with a tone running. If this happens, restart GIL interactively, and then ".bye" out of it, or issue a short .beep command. In the extremely unlikely case that the the problem now continues, then you will have to reboot your computer. In your CONFIG.SYS file, be sure to enable the ANSI.SYS device driver. GIL does NOT require a co-processor. (A later release may permit faster graphics using the co-processor.) GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams GIL (c) 1.01 COMMAND REFERENCE ----------------- GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams GENERAL NOTES ON COMMANDS: -------------------------- A command is given to GIL as only one type of entry. 1.) A GIL executable command starts with the period, or dot, "." 2.) A "comment" is any ASCII text entered where the first character in the first column is the "#" character. Comments will be ignored. 3.) Empty lines consisting entirely of whitespace are ignored. 4.) Any other lines of ASCII text beginning with other than the "." character will be treated as data or garbage, depending on the context. SPECIAL CHARACTERS ------------------ The use of "#" and "." have just been described. UPPER CASE AND LOWER CASE ------------------------- Commands can be either UPPER or LOWER case. In some commands requiring alphanumeric, non-numeric, data, such as the ".color" command for color specification, the alpha may be in UPPER or LOWER case also. The only case sensitive input is the data you specify for the text to be displayed in the ".text" command. ERROR MESSAGES -------------- In certain isolated cases when bad data or commands are entered, a two-tone beep will occur to signal the user that display is otherwise impossible. For example, it is possible for the color parameter of the hue command (such as BLACK) to cause display of the "GIL>" prompt to be in the same color as the background color (entered with the ".backdrop" command). After that, the user may get flustered and enter a new ".color" command with a misspelled color parameter. Since the error message cannot be displayed (it is also lost in the background color at this point) a two-tone beep is one way to indicate an error message. If bad command syntax occurs, error messages will be displayed on the screen. GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams GENERAL COMMAND STRUCTURE ------------------------- Most commands consist of the leading "." in column one, followed by the command name, with no intervening spaces, and then a series of numerical or text parameters. Except for extended commands, the command entry is concluded by typing the ENTER key. Therefore most command lines will be shorter than 80 columns. In fact, the program assumes a default maximum of 80 columns per ASCII line (40 for CGA). After the command keyword, parameters are entered. Commands and parameters can be separated by "white space", e.g. SPACE, TAB, and/or also by the COMMA. This should allow "easy" formatting of data by programs used to "assist" in generating polygons, lines, etc. Therefore, the following command structure exists for most of the commands: .command n1 n2 n3 n4 ... nk where "command" is the keyword, and n1 through nk are numerical or alphanumerical parameters. For the detailed command descriptions below, this structure is important to understand now. A few commands, such as .polygon and .wave, require something in addition: EXTENDED COMMANDS ----------------- Some commands, such as ".polygon" and ".wave", will require so much data that more than one line of data can be entered to fulfill the list. The lines of data coming after such a command line will (a) always be numeric, and (b) must be terminated with the final ".end" command. GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams # comment lines --------------- With a # as the first character in the line, ALL of the remaining line is disregarded. However, it is a useful way to place information in the file for debugging and explanation purposes. GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams .arc3 n1 n2 n3 n4 n5 n6 ----- -- -- -- -- -- -- Description This routine is based on the geometrical rule that a circle can be drawn through any three points on the plane, thus the name "arc" (draw an arc) concatinated with "3" (three points determine the circle). In this program the arc is drawn COUNTER-CLOCKWISE from the first set of viewpoint coordinates (n1, n2) to the third set of viewpoint coordinates (n5, n6). The important effects are caused by the second set of coordinates, (n3, n4), which determine the "bending" necessary to make the circle. NOTE: after the circle is calculated, the only part displayed is the part obeying the above rule. If the bending point is in the portion of the circle that would require drawing clockwise from (n1, n2) to (n5, n6) it will not actually be part of the arc. Rather it will be part of the gap. A problem can occur under certain conditions when the end points of the arc or the bending point fall on coordinates which cause division by zero. This can occur for instance when n1 = n5 or n2 = n6. There are other combinations that cause this also. Also, if the three points lie in a line, there is no way to determine if the arc is concave or convex. This program will examine the entered coordinates, and in certain cases "dither" the coordinates by adding in a small amount of random noise that is less than +/- 1.0 (width of one pixel in floating point). The net effect should amount to an indistinguishable error in the size of the arc. The default or most recent drawing color is used for this curve. Remarks Clipping at the edge of the viewport WILL occur for arcs drawn to be larger than the viewport. This can be used to advantage (like say you want to draw an artificial horizon), or for zooming into a drawing. See description of clipping elsewhere. If you want to draw the entire circle, then draw one arc as per above, and then enter a second command with the end points interchanged in the command line. See Also .color, .ellipse Defaults: n1 = 100, n2 = 100, n3 = 100, n4 = 100, n5 = 100, n6 = 100. Net effect: either nothing or a small dot is drawn, depending on the outcome of the random number routine. Bugs Aliasing on the edges of the arc is NOT removed. Very tiny circles will thus appear lumpy. Example .arc3 300 100 200 50 100 100 To draw a full circle, the gap is filled in with .arc3 100 100 200 50 300 100 GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams .aspect n1 ------- -- Description Used to correct for the differences in aspect ratio of different displays or adapters, such as VGA or HGC. Also, .aspect can be used to "stretch" or "crunch" a display for making "square" printouts with print utilities. The parameter n1 is a floating point number, usually in the range .7 to 1.5, used to expand or compress the vertical scale of the drawing for better looks on some displays. Numbers greater than 1.0 are expansions. Remarks See Also .require Bugs Any problems are caused by the attempt to be all things to all adapters. Example .aspect 1.3 GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams .backdrop n1 --------- -- Description Used to set/change the default color for the background color of the viewport. Lifetime of this command's effects last until the next .backdrop command. Remarks See previous pages for the color table used for the various graphics adapters. See also the notes on compatibility between adapters. See Also .color Bugs There are never enough colors. There is no orange. The backdrop color affects the way these colors are displayed, in ways you can best judge by experimentation. Example .backdrop , LTGRAY GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams .beep n1 ----- -- Description Used to sound the speaker for the time duration n1. n1 is an unsigned decimal integer. Units of n1 are approximately tenths of a second. Remarks Use of large values for n1 will result in LONG waits and possible stares from other people around you. See Also .pitch Bugs See Remarks. Can you wear out a speaker? Under some conditions (see text) aborting with CTRL-C or CTRL-BREAK may leave the speaker permanently ON. This usually should not be a problem, however. Example .beep 10 gives a one second tone. GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams .box n1 n2 n3 n4 (open box) ---- -- -- -- -- .fbox n1 n2 n3 n4 (filled box) ----- -- -- -- -- Description Used to draw a box, or rectangle, from coordinates of the first point (n1,n2) to the coordinates of the second point (n3,n4). Coordinates of both points are in viewport coordinates. Remarks The endpoints can lie outside the viewport. Active clipping will ensure that only the portion of the line inside the viewport will be shown. See Also .polygon, .color Defaults: n1 = 100, n2 = 100, n3 = 200, n4 = 200. Bugs Aliasing effects ("zaggies") are NOT eliminated by this program. Example .box 23 49 800 300 GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams .bye ---- Description This command is used to exit GIL and return the screen to the default DOS display. Remarks This command is the recommended way to exit GIL while in interactive mode. Using CTRL-C or CTRL-BREAK is possible, but not recommended and may result in confused screen setup or confused screen colors or a continuous speaker tone when DOS returns control, although these are very remote possibilities. See Also Bugs Example .bye GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams .cgatext n1 -------- -- Description This command is used to turn on a "fudge" factor for displaying non-CGA files on CGA adapters, when ".text" lines would normally call for characters in columns 41-80. This command, when n1 = ON, will cause all text from .text commands to be shifted to the left, such that the column address called for will be divided by exactly 2, and rounded down if necessary. That is, if the command ".text 10 50 Hello" is given, the result on the screen will effectively be ".text 10 25 Hello". Parameter n1 is not case sensitive and can be either: n1 = ON or n1 = OFF Remarks CGA screens are only half as wide (in pixels) as EGA, CGA, etc. Thus graphics, when scaled to fit CGA, will not line up with text, which is presently using row and columc text boundaries. In addition, CGA pixels are twice as large (huge) when compared to the other adapters, so even when text is placed only half as far across the screen, it will often be also too high when compared to the other adapters. See Also .text Bugs Therefore, per the remarks, the end result will only be close, but not exact, and often will still not yet be satifactory. Some incompatibilities between CGA and other adapters cannot be totally "fudged" away. Example .cgatext on GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams .circle n1 n2 n3 (line circle) ------- -- -- -- .fcircle n1 n2 n3 (filled circle) -------- -- -- -- Description Used to draw a circle in the viewport. The center of the circle is at x = n1, y = n2. The radius is n3. The default color is used for both the lined form and the filled disc form. Remarks Clipping at the edge of the viewport WILL occur for circles drawn to be larger than the viewport. This can be used to advantage (like say you want to draw an artificial horizon), or for zooming into a drawing. See description of clipping elsewhere. See Also .color, .ellipse Defaults The center is n1 = 150, n2 = 150, with a radius of n3 = 100. Bugs Aliasing on the edges of the circle is NOT removed. Very tiny circles will thus appear lumpy. Example .circle 250 283 100 GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams .color n1 ------ -- Description Used to set/change the default color for all drawing and filling operations that follow, until the next occurrence of a .color command. Note that only one parameter is accepted, and it must be a color per the table above, not a numeric value. The lifetime of this color is until the next .color command. This color ALSO affects the color of the text and command line displays, as well as error messages. It is not a good idea to make this color the same as the backdrop color. EXCEPTION: if you want to print the screen, making this color the same as the back- drop color will "hide" the command line, thus removing the annoyance of having the command line becoming part of the drawing printed out. Remarks See previous pages for the color table used for the various graphics adapters. See also the notes on compatibility between adapters. See Also .backdrop Bugs There are never enough colors. There is no orange. The backdrop color affects the way these colors are displayed, in ways you can best judge by experimentation. Example .color RED GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams .dot n1 n2 ---- -- -- Description This command "sets" one pixel on the screen using the current color (defined by the .color command) at the viewport location x = n1, y = n2. Remarks Can be used to place random dots in your colors of choice on the screen. See Also .color, .backdrop Bugs Not very efficient for setting large numbers of pixels. Example .pixel 83 237 GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams .ellipse n1 n2 n3 n4 n5 n6 (line ellipse) -------- -- -- -- -- -- -- .fellipse n1 n2 n3 n4 n5 n6 (filled ellipse) --------- -- -- -- -- -- -- Description Used to draw a ellipse in the viewport. The center of the ellipse is at x = n5, y = n6 in viewport coordinates. This routine can be used to draw an ellipse which is rotated by some arbitrary angle of n3 degrees around its center point. n1 = First axis length n2 = Aspect ratio relative to first axis. This is a floating point number from 0.0 to almost as large as you want. n3 = Inclination, in degrees, of the first axis from horizontal. n4 = step angle in degrees. The algorithm used depends on incrementing around the ellipse from 0 to 360 degrees every n4 degrees. When n4 = 1 there is sufficient detail that the ellipse looks smooth. Increments such as 5 or 10 degrees also usually look reasonable. However, increments such as 60 degrees can be used, which results in some interesting polygons. n5 = x axis location of center of ellipse in viewport coordinates. n6 = y axis location of center of ellipse in viewport coordinates. Remarks Clipping at the edge of the viewport WILL occur for ellipses drawn to be larger than the viewport. This can be used to advantage (like say you want to draw an artificial horizon), or for zooming into a drawing. See description of clipping elsewhere. Rotation of the ellipse is useful for generating interesting effects. See Also .color, .circle Defaults First axis length n1 = 250, Aspect ratio n2 = 1.00 First axis inclination = 0 degrees, Step angle = 5 degrees, Center is 500, 320. Bugs Aliasing on the edges of the ellipse is NOT removed. Very tiny ellipses will thus appear lumpy. Example .ellipse 200 .7 45 3 300 373 GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams .init ----- Description This command is used to clear the screen of all text and graphics. The effect is nearly the same as the DOS command CLS in DOS. Remarks See Also .backdrop Bugs Example .init GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams .line n1 n2 n3 n4 ----- -- -- -- -- Description Used to draw a line from the first point to the second point, in the current color. The viewport coordinates of the first point are x = n1, y = n2. The viewport coordinates of the second point are x = n3, y = n4. Remarks The endpoints can lie outside the viewport. Active clipping will ensure that only the portion of the line inside the viewport will be shown. See Also .polygon, .color Bugs Aliasing effects ("zaggies") are NOT eliminated by this program. Example .line 23 49 800 300 GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams .pitch n1 ------ -- Description Used to define/redefine the default pitch frequency for the tone generated by .beep. The value n1 is a decimal integer for a frequency in Hertz Remarks Low pitches are more tolerable with long beeps than high pitches. See Also .beep Bugs Based on timer chip in your computer, and the clock frequency of the timer chip. The actual pitch may end up different than expected if your computer's timer runs very fast or very slow. Example .pitch 440 Another Example .pitch 800 .beep 3 .beep 1 for the Morse code for "N" GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams .polygon (open polygon) -------- n1 n2 n3 n4 n5 n6 ... .end -- -- -- -- -- -- ---- .fpolygon (filled polygon) -------- n1 n2 n3 n4 n5 n6 ... .end -- -- -- -- -- -- ---- Description Polygon is used to draw polygons. The end points of the line segments of the polygon are determined by each PAIR of coordinates, starting with (n1, n2). The number of points determining the polygon can range up to 512. Polygons having only one point are "dots". Polygons having two points only are lines. (Interesting!) Three points determine a triangle, etc. However, the most useful features of polygons are when they are a) Irregular b) Involuted Such polygons can be used to draw almost any shape. See the provided examples for use of polygons. Polygons are drawn or filled with the default color or the color from the last .color command. Special Note: Data points are entered continuously, line after line, without regard for beginning a line with # or . In fact, the use of . or # should be avoided inside the data, but white space is permitted. The list is terminated with one final entry, ".end" as below. Remarks The .ellipse and .star commands in fact use the same display routines as polygon. See Also .end The .end command is used to terminate the list of points, after which the program counts up the list of points and begins drawing. Bugs The standard C graphics library is used for polygon filling. There are some examples (especially stars with large numbers of points) where filled polygons have slight zaggies on the edges that are caused by the standard library routines. Example .fpolygon 330 359 335 357 340 359 355 364 350 371 345 377 340 369 335 372 330 377 325 371 320 368 320 362 .end draws the three towed foot of a bird. GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams .require n1 -------- -- Description This command MUST be the first line in the data file IF it is used. However, it does not necessarily have to be used at all. This command is used to warn the user that the data that is going to come later is only compatible with (requires) a certain type of graphics adapter, e.g. it contains colors that only look right on a VGA. The possible choices for n1 are: VGA, OVGA, MCGA, EGA, OEGA, HGC, CGA, and OCGA. The n1 values are NOT case sensitive, however. When the "require" parameter (e.g. VGA) does not match the adapter in the computer (e.g. HGC) the program will prepare to terminate. Remarks This is merely a control feature to help unwary users by warning them if the file is incompatible with the graphics adapter in their computer. It is usually used to help users of monochrome adapters who would otherwise run color graphics data through the program and receive an all white set of polygons and graphics that would be fairly unglorious. It can also be used to indicate that the aspect ratio may not be right. E.g. graphics and text may become misaligned if run through the wrong adapter. The whole line can be removed from the file, or commented out with #, in order to remove its effect. See Also .aspect Bugs Example .require VGA GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams .star n1 n2 n3 n4 n5 (open star) ----- -- -- -- -- -- .fstar n1 n2 n3 n4 n5 (filled star) ------ -- -- -- -- -- Description Used to draw a star-shaped polygon. The coordinates of the center of the star are n1, n2. The radius of the outer circle of points of the star is n3. The radius of the points forming the notches is n4. The number of points of the star is n5. The range of n5 runs from 3 to 512. Remarks The endpoints can lie outside the viewport. Active clipping will ensure that only the portion of the line inside the viewport will be shown. A 512-pointed star is a lot of points! See Also .polygon, .color Defaults: n1 = 500, n2 = 300, n3 = 250, n4 = 80, n5 = 5. Bugs Aliasing effects ("zaggies") are NOT eliminated by this program. Especially, large filled stars with many points will have some strange effects due to the filled polygon routine from the C library. Example .star 500 300 200 50 28 GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams .text n1 n2 n3 ----- -- -- -- Description This command is used to place text on the screen in the middle of the graphics display. n1 = row coordinates of text ( 1 to 22 ). n2 = column coordinates of the first letter of the text ( 1 to 80 for all adapters except CGA, and 1 to 40 for CGA adaptors). n3 = any text in ASCII, even if containing more than one word. If you want this file to work with CGA as well as others, and you are editing it on something else besides CGA, try not to make the length of the text on n3 longer than 40 characters. Remarks Alignment with graphics can be somewhat problematic. These routines attempt to serve all graphics adapters. CGA adapters, which have such large text characters, will always be even more problematic. See Also .cgatext Bugs The C library used does not have the ability to output generic BIOS character generator text in just any location on the graphics screen. BIOS characters are forced to reside on text coordinates. This is a major problem, which until solved, makes alignment of text and graphics problematic, especially when this program attempts to work on all graphics adapters. "Personal Engineering" magazine recently discussed this issue. Real graphics fonts from the C compiler are available, but these require payment of a royalty to BITSTREAM, which is not going to be compatible with the idea here of free software. Examples .text 4 8 The quick brown fox jumped .text 7 20 ~We the people GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams .trace n1 ------ -- Description Trace is used to select whether or not to display the entire array of parameters from a ".polygon" or ".wave" command, or to skip the display beyond the first line. If trace is on, each line of parameters is displayed successively, as parsed, on line 23. If trace is not on, the parse is done "silently". Parameter n1 is not case sensitive and can be either: n1 = ON or n1 = OFF Remarks Trace is useful for finding "bad spots" in a parameter list. See Also .polygon and .wave Bugs Unfortunately, if the file contains a long list of coordinate parameters, turning on trace will consume more time while the display routines print the text one line at a time on line 23. Example .trace on GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams .wave ----- n1 n2 n3 n4 n5 n6 ... .end -- -- -- -- -- -- ---- Description Wave is used to draw waveforms or a long set of contiguous linked line segments. The end points of the line segments of the polygon are determined by each PAIR of coordinates, starting with (n1, n2). The number of points determining the waveform can range up to 512. For drawing graphs or waveforms, this routine does NOT perform curve fitting, smoothing, or draw with Bezier or B-spline techniques. SPECIAL NOTE: the y-azis coordinate system starts at the top of the screen, not the bottom. This should be taken into account when other programs are used to calculate the set of points and this program is used to graph the waveform, using .box, .fbox, .text, and .wave. Waves are drawn or filled with the default color or the color from the last .color command. Special Note: Data points are entered continuously, line after line, without regard for beginning a line with # or . In fact, the use of . or # should be avoided inside the data, but white space is permitted. The list is terminated with one final entry, ".end" as below. Remarks This is similar to the .polygon command. See Also .end The .end command is used to terminate the list of points, after which the program counts up the list of points and begins drawing. Bugs This may not be the most comfortable way to actually draw a graph of some data, since the y coordinate starts at the top of the screen, not the bottom. Example .box 1 1 600 400 .wave 1 200 100 160 200 230 300 180 400 330 500 200 599 400 .end GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams Possible future commands: Commands that make thick lines. But such commands need to execute very quickly! The only way to make thick lines right now is to draw them by laying down parallel lines. Commands to draw "waveforms" and "zig-zags" with cubic spline, Bezier spline, or B-spline methods. "Splines" are methods similar to drawing with a "french curve" on paper. Better graphics text characters. "Personal Engineering" magazine recently discussed this issue.